feat(spec): Add $self for identity-based referencing#451
feat(spec): Add $self for identity-based referencing#451frankkilcommins wants to merge 1 commit intoOAI:v1.1-devfrom
Conversation
handrews
left a comment
handrews
left a comment
There was a problem hiding this comment.
Thanks for doing this! Most of it looks great, a few minor bits plus RFC3986 base URI determination being a bit more complex than is stated here. Plus making it explicit that referencing an OAD by that OAD's $self requires examining potential target OADs for $self.
| This includes the parsing requirements of [JSON Schema Specification Draft 2020-12](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relative-references-in-arazzo-description-uris). | ||
| Reference targets include the Arazzo Object's [`$self`](#arazzoSelf) field (when present). | ||
|
|
||
| Implementations MUST NOT treat a reference as unresolvable before completely parsing all documents provided to the implementation as possible parts of the Arazzo Description. |
There was a problem hiding this comment.
There's something analogous to say here about the url field in the Source Description Object, which (for OAS 3.2 and later) MUST examine provided OADs form a $self matching that url field. You arlready note further down that this field, if relative, MUST be resolved against the Arazzo document's base URI ($self if present) as a URI, so this is just the other end of it: once it's non-relative, you need to resolve it to a document by the target document's identity if that is different from its location.
|
|
||
| Implementations MUST NOT treat a reference as unresolvable before completely parsing all documents provided to the implementation as possible parts of the Arazzo Description. | ||
|
|
||
| If only the referenced part of a document is parsed when resolving a reference, implementations may miss the `$self` field or Source Description URIs, causing references to resolve to unintended locations. The resulting behavior of fragmentary parsing is _undefined_ and NOT RECOMMENDED. |
There was a problem hiding this comment.
This language is present in the OAS because in Swagger/OAS 2.0, the expectation was to parse targets in isolation (more or less... it's not quite spelled out but that's how it often worked). And then it was completely ambiguous in 3.0. So 3.1.1+ and 3.2 have this language to let people know something changed. If Arazzo documents were always parsed as whole documents, this is probably more confusing than helpful. I have no idea what Arazzo tools do today, though.
| - If the [`$self`](#arazzoSelf) field is present and is a relative URI-reference, the base URI is the result of resolving `$self` against the retrieval URI (or other applicable base URI per RFC3986 Section 5.1). | ||
| - If the [`$self`](#arazzoSelf) field is not present, the base URI is the retrieval URI of the Arazzo Description document. |
There was a problem hiding this comment.
This wording makes it sound like the retrieval URI is the next place to look, which (per RFC3986) it is not. I'm nitpicking on this because it's a very persistent misconception, which is why the OAS says:
If $self is a relative URI reference, it is resolved against the next possible base URI source ([RFC3986] Section 5.1.2 – 5.1.4) before being used for the resolution of other relative URI references.
and then talks about the retrieval URI as the most common (but not next) place to find the base URI.
If you want use cases for the non-$self, non-retrieval URIs I can provide them.
|
|
||
| If a URI contains a fragment identifier, then the fragment MUST be resolved per the fragment resolution mechanism of the referenced document. | ||
|
|
||
| For JSON or YAML documents (including OpenAPI or AsyncAPI descriptions referenced via Source Descriptions), the fragment identifier SHOULD be interpreted as a JSON Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901). |
There was a problem hiding this comment.
I see this came from the OAS, but I just realized we have a slight bug here: Schema Objects can also declare plain name fragments. I'm not sure it's worth worrying about right now as I am not sure off the top of my head how to explain that part, but perhaps an issue to fix it before shipping? I just need to think on it for a little bit.
| - [Relative References in Arazzo Description URIs](#relative-references-in-arazzo-description-uris) | ||
| - [Schema](#schema) |
There was a problem hiding this comment.
I think you accidentally dropped "Relative References in API URLs" (that section looks good, btw, nice distinctions regarding Arazzo docs vs OAD docs vs APIs vs runtime expressions).
|
|
||
| ### Base URI From the Retrieval URI (No `$self`) | ||
|
|
||
| If the same document does not define `$self`: |
There was a problem hiding this comment.
I think the other examples from OAS Appendix F are needed here, as the retrieval URI is not the only possible additional source.
Adding more sources shouldn't break compatibility, because in the exceedingly unlikely scenario that anyone was actually parsing something where there's an encapsulating entity (e.g. multipart/related hypermedia archive format), there's no obvious "retrieval URI" anyway, so they're doing something else not defined by Arazzo. I think the bits about handling $id in Schema Objects are relevant for you as well.
2 participants
fixes #434